////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package fxplugins.core
{

import fxplugins.plugin.IPluginMap;
import fxplugins.registry.IExtensionRegistry;
import fxplugins.utility.IUtilityMap;

/**
 * The IComponentMap interface defines the Component Map's core programming
 * interface for initialization.
 * 
 * <p>The <code>manifest</code> allows the ability for clients to reflect
 * application specific configurations defined by the developer at compile time.
 * The component map can easily be extended to load this information and deceminate
 * the information in the same way it does at compile time.</p>
 * 
 * <p>The <code>pluginMap</code> allows the developer to specify a compile
 * time map of plugin component extension points and extensions. This map usually
 * holds extensions implementing a certain existing extenion point declared
 * at some point either compile time or runtime of the application.</p>
 * 
 * <p>The <code>utilityMap</code> allows the developer to specify a compile 
 * time map of plugin utilities that are needed and will be registered with 
 * the utility map. The design goal here was to separate manager utilities 
 * such as a popUp manager from a component extenstion such as a dialog popUp
 * component.</p>
 * 
 * <p><strong>Note:</strong> There is only one instance of the <code>manifest</code>,
 * <code>pluginMap</code> and <code>utilityMap</code> per application. There
 * are component map utilities that allow additional registry of plugin utilities 
 * and plugin extension points and extensions during runtime (IExtensionRegistry).</p>
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 */
public interface IComponentMap
{
	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------
	
	//----------------------------------
	//  application
	//----------------------------------
	
	/**
	 * Returns the Application instance for the specific component map.
	 * 
	 * <p>There can be multiple applications loaded as modules and these could contain
	 * their own component map.</p>
	 * 
	 * <p><strong>NOTE:</strong> it is important to note, that there will be an
	 * extensionRegistry and injector for each componentMap, knowing who has what
	 * is up the the application domain's logic.</p>
	 */
	function get application():Object;
	
	//----------------------------------
	//  manifest
	//----------------------------------
	
	/**
	 * The manifest specifies application configurations at startup.
	 * 
	 * <p>This instance is usually an implementation with application specific
	 * properties.</p>
	 */
	function get manifest():IComponentManifest;
	
	/**
	 * @private
	 */
	function set manifest(value:IComponentManifest):void;
	
	//----------------------------------
	//  pluginMap
	//----------------------------------
	
	/**
	 * The startup plugin map that contains needed plugin extension points and
	 * extenions for the application.
	 */
	function get pluginMap():IPluginMap;
	
	/**
	 * @private
	 */
	function set pluginMap(value:IPluginMap):void;
	
	//----------------------------------
	//  utilityMap
	//----------------------------------
	
	/**
	 * The startup utility map that contains needed plugin utilities for the 
	 * application.
	 * 
	 * <p>The utility map will contain managers of singletons that require
	 * a provider that will instantiate each utility.</p>
	 */
	function get utilityMap():IUtilityMap;
	
	/**
	 * @private
	 */
	function set utilityMap(value:IUtilityMap):void;
	
	//----------------------------------
	//  extensionRegistry
	//----------------------------------
	
	/**
	 * The single instance of the extension registry that tracks all extension
	 * points, extensions and extension descriptors.
	 */
	function get extensionRegistry():IExtensionRegistry;
	
	//----------------------------------
	//  injector
	//----------------------------------
	
	/**
	 * The single instance of the injector, this will be application 
	 * implementation specific.
	 */
	function get injector():IComponentInjector;
}
}